Generated code - DataAccessAdapter Functionality, Adapter

Preface

For the Adapter template group, LLBLGen Pro will generate two VS.NET projects. This section describes the DataAccessAdapter class which is located in the database specific project and which is the class that performs all database activity for entities, typed lists, typed views and stored procedure calls: the DataAccessAdapter object provides the persistence service to the developer. For successful usage of the Adapter template group, it's important to understand which functionality is offered by the DataAccessAdapter class and this section shows a brief overview of that functionality. In-depth discussions of various aspects of the functionality can be found in the remainder of the Adapter documentation.

For the full API offered by DataAccessAdapter, please see the LLBLGen Pro runtime framework reference manual (separate download) for the interface IDataAccessAdapter and the class DataAccessAdapterBase.

Functionality

The DataAccessAdapter class is the single class you'll need to interact with the database to fill entities, store changed data, call a stored procedure, start a transaction etc. Below is a brief overview of the various aspects of the DataAccessAdapter class.

note Note:
The DataAccessAdapter class is not thread safe and should not be used as such. Each thread should use its own instance, it's not safe to share a DataAccessAdapter instance among multiple threads. Creating a new DataAccessAdapter instance is very fast though (almost no overhead), so re-creating one for each query is recommended.
Connection strings
The DataAccessAdapter reads the connection string automatically from the *.config file available, however you can also supply a connection string to a constructor overload of DataAccessAdapter. This means that you can target different databases under different users on a per-call basis.
Multi-tenancy support: catalog specific persistence info (SQL Server, Sybase ASE, MySQL)
Adapter uses catalog specific persistence information. This means that the catalog name is generated into the persistence information. The result of this is that although the connection string might contain a different catalog name, the queries will use the catalog name generated into the persistence information for each field and database object (table/view). This can be very helpful in the scenario with multiple catalogs per project, but might not be what you want in some situations. You can overwrite the catalog name to be used on a per-call basis by specifying catalog name overwriting information to the DataAccessAdapter's constructor or set some properties later on. Below is an overview of the options available to you:

You can also specify extra appSettings add-tags in your application's .config file's appSettings tag to set these overwrites. This is provided for backwards compatibility, and not recommended.

Add an add-tag with CatalogNameUsageSetting as value for the key and for the value one of the following: "0" (default), "1" (forceName) or "2" (clear), and an add-tag CatalogNameToUse, which should have as value the catalog name to use for each database call.

Example: (which will force a catalog name write on all database calls and will use the name "MyProductionCatalog".)

<configuration>
	<appSettings>
		<add key="Main.ConnectionString" value="data source=..."/>
		<add key="CatalogNameUsageSetting" value="1"/>
		<add key="CatalogNameToUse" value="MyProductionCatalog" />
		...
	</appSettings>
</configuration>

If you've specified these settings in your application's *.config file (web.config or app.config file (which results in executable name.exe.config)), you can just use the default DataAccessAdapter constructors and with each call these values are read from the config file. If you specify catalogNameToUse and catalogNameUsageSetting in the constructor of the DataAccessAdapter class and you specify for catalogNameUsageSetting something else than CatalogNameUsage.Default, the values specified in the *.config file will be ignored for that particular DataAccessAdapter instance, so it is still possible to override the settings specified in the *.config file on a per-call basis. Be aware that this is provided for backwards compatibility. See Application configuration through .config files for a more flexible solution.

note Note:
There is another way to overwrite catalog information, which is more efficient, and is required if you have multiple catalogs in your project. Please see Application configuration through .config files for more details.
Multi-tenancy support: Schema specific persistence info (DB2, Oracle, PostgreSql, SQL Server, Sybase ASA, Sybase ASE)
Adapter uses schema specific persistence information. This means that the schema name is generated into the persistence information and that the queries will use the schema name generated into the persistence information for each field and database object (table/view). This can be very helpful, but might not be what you want in some situations, like when you've defined global synonyms for tables in a particular schema and you want the generated code to target these synonyms in production. Having the ability to change the schema name at runtime can also be helpful if you want to target multiple schemas with the same schema objects. You can overwrite the schema name to be used on a per-call basis by specifying schema name overwriting information to the DataAccessAdapter's constructor or set some properties later on. This all sounds familiar from the previous catalog name overwriting paragraph, so the schema name overwriting options look the same as for the catalog name ovewriting options. Below is an overview of the options you have:

You can also specify extra appSettings add-tags in your application's .config file's appSettings tag to set these overwrites (not available on SqlServer, for SqlServer, use the preferred way explained in the Application configuration through .config files section). This is provided for backwards compatibility, and not recommended.

Add an add-tag with SchemaNameUsageSetting as value for the key and for the value one of the following: "0" (default), "1" (forceName) or "2" (clear), and an add-tag SchemaNameToUse, which should have as value the schema name to use for each database call.

Example: (which will force a schema name write on all database calls and will use the name "MyProductionSchema".)

<configuration>
	<appSettings>
		<add key="Main.ConnectionString" value="data source=..."/>
		<add key="SchemaNameUsageSetting" value="1"/>
		<add key="SchemaNameToUse" value="MyProductionSchema" />
		...
	</appSettings>
</configuration>

If you've specified these settings in your application's *.config file (web.config or app.config file (which results in executable name.exe.config)), you can just use the default DataAccessAdapter constructors and with each call these values are read from the config file. If you specify schemaNameToUse and schemaNameUsageSetting in the constructor of the DataAccessAdapter class and you specify for schemaNameUsageSetting something else than SchemaNameUsage.Default, the values specified in the *.config file will be ignored for that particular DataAccessAdapter instance, so it is still possible to override the settings specified in the *.config file on a per-call basis. Be aware that this is provided for backwards compatibility. See Application configuration through .config files for a more flexible solution.

note Note:
There is another way to overwrite schema information, which is more efficient, and is required if you have multiple schemas in your project. Please see Application configuration through .config files for more details.
Command timeouts
Sometimes a query can take a long time to complete, for example with data-processing stored procedure calls. With Adapter, you can set the timeout for each query on a per-call basis, using the property DataAccessAdapter.CommandTimeOut. The default is 30 (seconds). Firebird and SqlServer CE don't support command timeouts and a CommandTimeOut value is ignored.
Connection control
It can be useful to open a connection and keep it open for multiple actions and then close it. This can give extra performance, especially in code where multiple database fetches are used in one routine. The property KeepConnectionOpen is used to set this behaviour.
Recursive saves
The DataAccessAdapter object supports recursive saves, which is the default. This also works with entity collections. The logic automatically determines the order in which actions need to take place. For example: This synchronization of FK-PK values is already done at the moment you set a property to a reference of an entity object, for example myOrder.Customer = myCustomer, if the entity (in this case myCustomer) is not new. Synchronization is also performed after a save action, so identity/sequenced columns are also synchronized.
Fetching/deleting/saving entities/typed lists/typed views
The DataAccessAdapter object offers full support for fetching/deleting/saving entities and entity collections and filling typed lists and typed views. It also supports, as SelfServicing, directly updating/deleting of entities in the persistent storage.
Calling stored procedures
Calling stored procedures is fully supported by the DataAccessAdapter object. The DataAccessAdapter object controls the transactions, so you can now call a stored procedure inside an existing transaction.
Transactions
Adapter fully supports ADO.NET transactions and System.Transactions based distributed transactions. You can start a transaction using the DataAccessAdapter class and all actions performed after that are executed inside that transaction. It doesn't matter if you fetch collections, typed lists, delete / save entities or call a stored procedure. All multi-entity affecting actions like recursive saves and the save of an entity collection, or the deletion of a set of entities, is, as in SelfServicing, always performed inside a transaction: if an existing transaction is present, that transaction is used, otherwise a new transaction is created and used.
Intercepting activity calls
The DataAccessAdapter class has functionality on board to let you perform actions during various stages of a process, for example right before a save action, or when an entity is fetched. These methods start with 'On' and are defined as virtual and are by definition implemented as an empty method (no-op). Please consult the LLBLGen Pro reference manual and inspect the DataAccessAdapterBase class' members for the details about these methods. DataAccessAdapterBase is the base class for every DataAccessAdapter class.

If you want to perform a given action when one of these methods are called, you can override them in the generated DataAccessAdapter class, preferably using the methods discussed in Adding your own code to the generated classes. Please consult the LLBLGen Pro reference manual, available in the LLBLGen Pro installation folder, for details about these methods (DataAccessAdapterBase.On..) when they're called and what is passed in.
ArithAbort flag (SqlServer only)
If an entity is saved into a table which is part of an indexed view, SqlServer requires that SET ARITHABORT ON is specified prior to the actual save action. You can tell LLBLGen Pro to set that option, by calling the method DataAccessAdapter.SetArithAbortFlag(bool) method. After each SQL statement a SET ARITHABORT OFF statement will be executed if the ArithAbort flag is set to true. Setting this flag affects all INSERT statements following the call to SetArithAbortFlag(), until you call that method again.
DQE Compatibility mode (SqlServer only)
The SQL Server DQE is used for all SQL Server versions and it therefore uses a compatibility mode to generate the SQL which is compatible with the used database version. To set the default compatibility mode of the SqlServer DQE in code, you can use the DataAccessAdapter method SetSqlServerCompatibilityLevel, as shown in the following example which sets the compatibility mode to SqlServer 2000:

// C#
DataAccessAdapter.SetSqlServerCompatibilityLevel( SqlServerCompatibilityLevel.SqlServer2000 );
' VB.NET
DataAccessAdapter.SetSqlServerCompatibilityLevel( SqlServerCompatibilityLevel.SqlServer2000 )

The different compatibility modes are: The default is SqlServer2005, which means 2005 and higher. The integer values have to be used when you're using the .config file parameter. See for more details about that parameter Generated code - Application configuration through .config files.

There's also a per-instance compatibility setting, so you can use one DataAccessAdapter instance with a different compatibility level than another. To do that, set the instance property CompatibilityLevel to one of the SqlServerCompatibilityLevel values. Setting this property will, for that DataAccessAdapter instance, override the default compatibility level.

See Database specific features, SQL Server Specific: compatibility mode,  for details about the SQL specific effects each compatibility mode has.
 
LLBLGen Pro Runtime Framework v3.5 documentation. ©2012 Solutions Design bv